Explorez l'objet Duration de l'API Temporal de JavaScript pour des calculs d'intervalles de temps précis et intuitifs, de l'usage basique aux scénarios avancés.
Maîtriser Temporal Duration de JavaScript : Un Guide Complet sur le Calcul d'Intervalles de Temps
L'API Temporal de JavaScript représente une avancée significative dans la gestion des dates et des heures. L'un de ses composants principaux est l'objet Duration, conçu spécifiquement pour représenter des intervalles de temps. Contrairement à l'objet Date traditionnel qui souffre de mutabilité et de complexités liées aux fuseaux horaires, Duration offre une manière plus propre, plus précise et internationalement consciente de travailler avec des durées. Ce guide complet explorera l'objet Duration en détail, couvrant tout, de l'utilisation de base aux scénarios avancés.
Qu'est-ce que Temporal Duration ?
Un Temporal.Duration représente une durée de temps, indépendamment de tout système de calendrier ou fuseau horaire spécifique. Il se concentre uniquement sur la quantité de temps, exprimée en années, mois, jours, heures, minutes, secondes et fractions de seconde. Pensez-y comme "5 ans, 3 mois et 2 jours", plutôt que "du 1er janvier 2023 au 3 mars 2028".
Cette distinction est cruciale car les durées sont intrinsèquement relatives. Ajouter une durée à une date spécifique donnera toujours une nouvelle date, mais le résultat précis dépend du système de calendrier et de la date de départ. Par exemple, ajouter un mois au 31 janvier donne des dates différentes selon que l'année est bissextile ou non.
Créer des objets Duration
Il existe plusieurs façons de créer des objets Temporal.Duration :
1. À partir de composants
La manière la plus directe est d'utiliser la méthode Temporal.Duration.from avec un objet contenant les composants souhaités :
const duration1 = Temporal.Duration.from({ years: 1, months: 6, days: 15 });
console.log(duration1.toString()); // Sortie : P1Y6M15D
const duration2 = Temporal.Duration.from({ hours: 8, minutes: 30, seconds: 12, milliseconds: 500 });
console.log(duration2.toString()); // Sortie : PT8H30M12.5S
const duration3 = Temporal.Duration.from({ years: 2, days: -5, seconds: 30 });
console.log(duration3.toString()); // Sortie : P2YT-5S30S
Notez que vous pouvez utiliser des valeurs négatives pour représenter des durées qui remontent dans le temps.
2. À partir d'une chaîne ISO 8601
La méthode Temporal.Duration.from accepte également une chaîne de durée ISO 8601 :
const duration4 = Temporal.Duration.from('P3Y2M10DT5H30M');
console.log(duration4.toString()); // Sortie : P3Y2M10DT5H30M
const duration5 = Temporal.Duration.from('PT1H15M30S');
console.log(duration5.toString()); // Sortie : PT1H15M30S
const duration6 = Temporal.Duration.from('P-1Y');
console.log(duration6.toString()); // Sortie : P-1Y
Le format de durée ISO 8601 est P[années]Y[mois]M[jours]D[T[heures]H[minutes]M[secondes]S]. Le 'P' indique une période (durée), et le 'T' sépare les composants de date et d'heure.
3. Utiliser le constructeur
Vous pouvez également utiliser le constructeur Temporal.Duration directement :
const duration7 = new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 8);
console.log(duration7.toString()); // Sortie : P1Y2M3W4DT5H6M7S8ms
Les arguments du constructeur sont dans l'ordre : years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds.
Propriétés de Duration
Une fois que vous avez un objet Duration, vous pouvez accéder à ses composants en utilisant ses propriétés :
const duration = Temporal.Duration.from('P1Y2M3DT4H5M6S');
console.log(duration.years); // Sortie : 1
console.log(duration.months); // Sortie : 2
console.log(duration.days); // Sortie : 3
console.log(duration.hours); // Sortie : 4
console.log(duration.minutes); // Sortie : 5
console.log(duration.seconds); // Sortie : 6
console.log(duration.milliseconds); // Sortie : 0
console.log(duration.microseconds); // Sortie : 0
console.log(duration.nanoseconds); // Sortie : 0
Arithmétique des durées
L'objet Duration fournit des méthodes pour effectuer des opérations arithmétiques :
1. Ajouter des durées
Utilisez la méthode add pour additionner deux durées :
const duration1 = Temporal.Duration.from('P1Y2M');
const duration2 = Temporal.Duration.from('P3M4D');
const sum = duration1.add(duration2);
console.log(sum.toString()); // Sortie : P1Y5M4D
2. Soustraire des durées
Utilisez la méthode subtract pour soustraire une durée d'une autre :
const duration1 = Temporal.Duration.from('P1Y2M');
const duration2 = Temporal.Duration.from('P3M4D');
const difference = duration1.subtract(duration2);
console.log(difference.toString()); // Sortie : PPT11M-4D
3. Négation d'une durée
Utilisez la méthode negated pour inverser le signe de tous les composants d'une durée :
const duration = Temporal.Duration.from('P1Y2M-3D');
const negatedDuration = duration.negated();
console.log(negatedDuration.toString()); // Sortie : P-1YT-2M3D
4. Valeur absolue d'une durée
Utilisez la méthode abs pour obtenir une durée avec tous les composants positifs :
const duration = Temporal.Duration.from('P-1YT2M-3D');
const absoluteDuration = duration.abs();
console.log(absoluteDuration.toString()); // Sortie : P1YT2M3D
5. Multiplier une durée
Utilisez la méthode multiply pour multiplier une durée par un nombre :
const duration = Temporal.Duration.from('PT1H30M');
const multipliedDuration = duration.multiply(2.5);
console.log(multipliedDuration.toString()); // Sortie : PT3H45M
6. Arrondir une durée
Utilisez la méthode round pour arrondir une durée à une unité spécifique. Cela nécessite de fournir une option relativeTo, qui peut être un Temporal.PlainDateTime ou Temporal.ZonedDateTime, car certaines unités (comme les mois et les années) ont des longueurs variables.
const duration = Temporal.Duration.from('P1DT12H30M');
const relativeTo = Temporal.PlainDateTime.from('2024-01-01T00:00:00');
const roundedDuration = duration.round({ smallestUnit: 'days', relativeTo });
console.log(roundedDuration.toString()); // Sortie : P2D
Dans cet exemple, 1 jour et 12 heures sont arrondis Ă 2 jours.
Comparer des durées
Vous pouvez comparer deux durées en utilisant la méthode compare. Cependant, gardez à l'esprit que les durées avec des unités mixtes (par exemple, des années et des jours) ne peuvent pas être comparées de manière fiable sans un contexte relatif (une date et un calendrier spécifiques). La fonction compare retourne :
- -1 si duration1 est inférieure à duration2
- 0 si duration1 est égale à duration2
- 1 si duration1 est supérieure à duration2
const duration1 = Temporal.Duration.from('PT1H');
const duration2 = Temporal.Duration.from('PT30M');
console.log(Temporal.Duration.compare(duration1, duration2)); // Sortie : 1
console.log(Temporal.Duration.compare(duration2, duration1)); // Sortie : -1
console.log(Temporal.Duration.compare(duration1, Temporal.Duration.from('PT1H'))); // Sortie : 0
const duration3 = Temporal.Duration.from('P1M');
const duration4 = Temporal.Duration.from('P30D');
// La comparaison directe de duration3 et duration4 lèvera une erreur dans de nombreux moteurs
// à moins que 'relativeTo' ne soit spécifié, car la longueur d'un mois n'est pas constante.
Exemples pratiques et cas d'utilisation
L'objet Temporal.Duration est incroyablement polyvalent et peut être utilisé dans un large éventail d'applications :
1. Calculer la durée d'un projet
Imaginez que vous gérez un projet avec une date de début et une date de fin. Vous pouvez utiliser Temporal.PlainDate et Temporal.Duration pour calculer la durée du projet :
const startDate = Temporal.PlainDate.from('2024-01-15');
const endDate = Temporal.PlainDate.from('2024-03-20');
const duration = endDate.since(startDate);
console.log(duration.toString()); // Sortie : P1M5D
2. Planifier des événements récurrents
Vous pouvez utiliser Temporal.Duration pour définir la fréquence des événements récurrents, tels que les réunions hebdomadaires ou les rapports mensuels :
const eventFrequency = Temporal.Duration.from({ weeks: 1 });
let nextEventDate = Temporal.PlainDate.from('2024-01-22');
for (let i = 0; i < 5; i++) {
console.log(`Événement ${i + 1}: ${nextEventDate.toString()}`);
nextEventDate = nextEventDate.add(eventFrequency);
}
// Sortie :
// Événement 1: 2024-01-22
// Événement 2: 2024-01-29
// Événement 3: 2024-02-05
// Événement 4: 2024-02-12
// Événement 5: 2024-02-19
3. Calculer l'âge
Bien que le calcul précis de l'âge nécessite de gérer les années bissextiles et les différents systèmes de calendrier, Temporal.Duration peut fournir une bonne approximation :
const birthDate = Temporal.PlainDate.from('1990-05-10');
const today = Temporal.PlainDate.from('2024-02-15');
const ageDuration = today.since(birthDate);
console.log(`Âge approximatif : ${ageDuration.years} ans, ${ageDuration.months} mois, ${ageDuration.days} jours`);
4. Calculs tenant compte des fuseaux horaires : Durées de vol
Pour les applications mondiales, la gestion des fuseaux horaires est essentielle. Envisagez de calculer la durée des vols entre différents fuseaux horaires :
const departureZonedDateTime = Temporal.ZonedDateTime.from('2024-03-15T10:00:00[America/Los_Angeles]');
const arrivalZonedDateTime = Temporal.ZonedDateTime.from('2024-03-16T14:30:00[Europe/London]');
const flightDuration = arrivalZonedDateTime.since(departureZonedDateTime);
console.log(`Durée du vol : ${flightDuration.hours} heures, ${flightDuration.minutes} minutes`);
console.log(flightDuration.toString());
Cet exemple montre comment Temporal.ZonedDateTime, combiné avec .since(), s'ajuste automatiquement aux différences de fuseaux horaires, fournissant une durée de vol précise.
5. Suivi des accords de niveau de service (SLA)
De nombreux services en ligne promettent des garanties de disponibilité. Vous pouvez utiliser `Temporal.Duration` pour définir et suivre ces accords.
const slaGuarantee = Temporal.Duration.from('PT99H59M59S'); // Presque 100 heures
const downtime = Temporal.Duration.from('PT1H');
if (downtime.compare(slaGuarantee) > 0) {
console.log("SLA non respecté !");
} else {
console.log("SLA respecté.");
}
Considérations avancées
1. Ambiguïté des mois et des années
Comme mentionné précédemment, la longueur des mois et des années peut varier. Lors de l'exécution de calculs impliquant ces unités, il est souvent nécessaire de fournir un contexte relatif en utilisant Temporal.PlainDateTime ou Temporal.ZonedDateTime. Ceci est particulièrement important lors de l'arrondissement ou de la comparaison des durées.
2. Systèmes de calendrier
L'API Temporal prend en charge différents systèmes de calendrier. Par défaut, elle utilise le calendrier ISO 8601, qui est le plus largement utilisé. Cependant, vous pouvez spécifier d'autres systèmes de calendrier lors de la création d'objets Temporal.PlainDate ou Temporal.ZonedDateTime. Les durées restent indépendantes du calendrier ; elles représentent une quantité de temps.
3. Mises à jour de la base de données des fuseaux horaires
Les règles des fuseaux horaires peuvent changer avec le temps pour des raisons politiques ou géographiques. Il est crucial de maintenir votre base de données de fuseaux horaires à jour pour garantir des calculs précis, en particulier lorsque vous travaillez avec Temporal.ZonedDateTime. Les environnements d'exécution JavaScript modernes gèrent généralement cela automatiquement, mais dans certains environnements, vous devrez peut-être mettre à jour la base de données manuellement.
Meilleures pratiques
- Utilisez les chaînes de durée ISO 8601 pour la sérialisation et l'échange de données. Cela garantit l'interopérabilité et évite l'ambiguïté.
- Préférez
Temporal.Durationpour représenter les intervalles de temps, plutôt que de calculer directement la différence entre deux objetsDate. Cela conduit à un code plus propre et plus facile à maintenir. - Soyez conscient de l'ambiguïté des mois et des années, et fournissez toujours un contexte relatif lorsque cela est nécessaire.
- Utilisez
Temporal.ZonedDateTimepour les calculs tenant compte des fuseaux horaires. - Gardez votre base de données de fuseaux horaires à jour.
- Lorsque vous comparez des durées avec des unités mixtes, utilisez toujours
roundavec un contexte relatif pour garantir une comparaison précise.
Conclusion
L'objet Temporal.Duration offre un moyen puissant et intuitif de travailler avec des intervalles de temps en JavaScript. En comprenant ses propriétés, ses méthodes et les meilleures pratiques, vous pouvez écrire un code plus robuste, plus précis et internationalement conscient. L'API Temporal, et l'objet Duration en particulier, représentent une avancée significative dans la gestion des dates et des heures en JavaScript, facilitant la création d'applications à la fois précises et pertinentes à l'échelle mondiale. Adoptez l'API Temporal et libérez son potentiel pour simplifier vos calculs liés au temps.
À mesure que l'API Temporal continue d'évoluer, restez informé des nouvelles fonctionnalités et des mises à jour. La proposition officielle ECMAScript et la documentation associée sont d'excellentes ressources pour rester à jour.